Standard formats for BBC files and disk images v 0.83
-----------------------------------------------------
[ N.B. This specification was originally included with bbcim v0.83 ]

Note: optional arguments are in square  brackets, '|' denotes a choice
between arguments.


THE ARCHIVE FILE FORMAT:
------------------------
(i.e. the standard format for/of files in the BBC micro archive of
software on my website)

[ N.B.  At the  time of writing  this down  (1997), my BBC  archive of
software was  almost all the software  for the BBC  micro available on
the internet (Robert  Schmidt's archive was mostly a  mirror of what I
put up), and I  wanted to get rid of diskimages so  you could pick and
choose software to put into a  disk yourself. So, 'the archive' was my
archive of BBC software. ]


  Complementing  a  bare  BBC  file  'ELITE'  is  the  attribute  file
'ELITE.inf' , which  is a text file containing  '$.ELITE FF0E00 FF8023
Locked CRC=XXXX NEXT  ELITEdata'.  ELITE is just the  name used on the
host  system  (as  BBC  files  often  contain  characters  that  other
filesystems can't  handle such  as '/') and  $.ELITE in  the attribute
file is the real name.

  In general we have:
  - A BBC file, 'myprog'
  - A text file 'myprog.inf' which contains:

{TAPE <tfs_filename> | <dfs_filename>} <load address> <exec address> [<file length>] ['Locked'] CRC=<xxxx> [NEXT <next filename>]

  Arguments are separated by spaces.

  Cassette names can be used in 2 ways;
  1. translated to $.<cassette_name> (i.e.  max 12 chars)
  2. TAPE <cassette name>

  Note that for complete  accuracy, TAPE <cassette name> is preferable
as it identifies a file as a TAPE file, where 'Locked' has a different
meaning to that for disks, and NEXT can be used (see below).

  Programs  handling  archive  format  files  should be  aware  of  12
character filenames from tapes ($.tape-name) and should rename them if
necessary.

  NEXT gives the next expected filename on the tape, which may be used
for  CHAIN"" or  *RUN  as used  on  cassette systems,  or  to put  the
programs back  on a tape  in the correct  order, so a  file containing
TAPE should contain  NEXT too (unless it's the  last file).  Note that
<next  filename> used for  NEXT must  be a  host filename,  as several
files can have the same name on tape!

  <load address> and <exec address> are hexadecimal strings (without a
language dependant identifier), e.g. FFFF8023.

  <file length> is also a hexadecimal string and may be included after
<exec address>) but is unnecessary.

  The file attribute 'Locked' may be abbreviated to 'L'.

  After 'CRC=' follows the bare file's CRC, as a hexadecimal string of
up to four digits.
  The CRC  is calculated  with the algorithm  from the BBC  user guide
p. 399  (The same  algorithm as  used in the  cassette and  rom filing
system).  It is included for various reasons (to check file conversion
software, serial- or disk- file transfer to/from a BBC, etc.). See the
appendix for a sample implementation.

  Host filenames: It is recommended that files only use ASCII and none
of the following  characters (due to the way they are  used in various
operating systems): \ / : * ? " < > | . ` '


THE ARCHIVE DISK FORMAT:
------------------------
  Given a BBC  disk image, e.g. 'games', we have an accompanying  file
('games.dsk'), which contains the following information:

 '<disktype> <sides> <tracks>T <sectorspertrack>S <bytespersector>B'

e.g. DFS SS 40T 10S 256B.

  After this line, any information about the disk image can be placed.
This should  be ignored by utilities  that only need  the disk format.

=> Suggestions of useful standard information to put there?

  If there's  no '.dsk' file, utilities should consider the disk image
to be 'DFS SS 80T 10S 256B', i.e. standard Acorn DFS.


Appendix: The CRC algorithm, example C code:
--------------------------------------------

long bbcim_data_crc(void *data, int length) {
	int  i;
	unsigned char *d = (unsigned char *) data;
	unsigned int crc;

	crc = 0;

	for (i=0; i<length; i++) {
		int  k;

		crc ^= ((*d++) << 8);
		for(k=0; k<8; k++) {
			if (crc & 32768) crc = (((crc ^ 0x0810) & 32767) << 1)+1;
			else crc <<= 1;
		}
	}

	return crc;
}

----

Wouter Scholten , 16-8-1997 & 18-4-2001

Email: swhs-web@xs4all.nl
Web page: http://wouter.bbcmicro.net/

(previous email addresses:
   whs@hccnet.nl,
   wouter.scholten@wanadoo.nl,
   whs@xs4all.nl,
   wouters@cistron.nl)
